<!DOCTYPE html>
<html lang="en">
<head>
  <title>Apache Ignite Cluster Manager for Vert.x - Vert.x</title>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta content="width=device-width, initial-scale=1.0" name="viewport">
  <meta content="Vert.x is a tool-kit for building reactive applications on the JVM." name="description">
  <link href="http://vertx.io/stylesheets/docs.css" media="screen" rel="stylesheet">
  <link href="http://vertx.io/stylesheets/font-awesome.min.css" media="screen" rel="stylesheet">
  <link href="http://vertx.io/javascripts/styles/rainbow.min.css" media="screen" rel="stylesheet">
  <!-- IE 6-8 support of HTML 5 elements -->
  <!--[if lt IE 9]>
  <script src="http://static.jboss.org/theme/js/libs/html5/pre3.6/html5.min.js"></script>
  <![endif]-->

  <link rel="apple-touch-icon" sizes="57x57" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-57x57.png">
  <link rel="apple-touch-icon" sizes="60x60" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-60x60.png">
  <link rel="apple-touch-icon" sizes="72x72" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-72x72.png">
  <link rel="apple-touch-icon" sizes="76x76" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-76x76.png">
  <link rel="apple-touch-icon" sizes="114x114" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-114x114.png">
  <link rel="apple-touch-icon" sizes="120x120" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-120x120.png">
  <link rel="apple-touch-icon" sizes="144x144" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-144x144.png">
  <link rel="apple-touch-icon" sizes="152x152" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-152x152.png">
  <link rel="apple-touch-icon" sizes="180x180" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-180x180.png">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-32x32.png" sizes="32x32">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/android-chrome-192x192.png" sizes="192x192">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-96x96.png" sizes="96x96">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-16x16.png" sizes="16x16">
  <link rel="manifest" href="http://vertx.io/assets/favicons/vertx-favicon-7/manifest.json">
  <link rel="mask-icon" href="http://vertx.io/assets/favicons/vertx-favicon-7/safari-pinned-tab.svg" color="#5bbad5">
  <meta name="msapplication-TileColor" content="#7d3194">
  <meta name="msapplication-TileImage" content="http://vertx.io/assets/favicons/vertx-favicon-7/mstile-144x144.png">
  <meta name="theme-color" content="#ffffff">

  <link href="http://fonts.googleapis.com/css?family=Ubuntu:400,500,700,400italic" rel="stylesheet" type="text/css">
  <link rel="alternate" type="application/rss+xml" title="RSS"
     href="http://vertx.io/feed.xml">
  <script>
    (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
    })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
    ga('create', 'UA-30144458-1', 'auto');
    ga('create', 'UA-71153120-1', 'auto', 'tracker');
    ga('send', 'pageview');
    ga('tracker.send', 'pageview');
  </script>
</head>
<body>

<a href="http://www.reactivemanifesto.org/" id="reactive-manifesto-banner">
  <img style="border: 0; position: fixed; right: 0; top:0; z-index: 9000"
    src="http://d379ifj7s9wntv.cloudfront.net/reactivemanifesto/images/ribbons/we-are-reactive-black-right.png">
</a>

<a id="skippy" class="sr-only sr-only-focusable" href="#content"><div class="container"><span class="skiplink-text">Skip to main content</span></div></a>

<header class="navbar navbar-default navbar-static-top" id="top" role="banner">
  <div class="container">
    <div class="navbar-header">
      <button class="navbar-toggle collapsed" type="button" data-toggle="collapse" data-target="#vertx-navbar-collapse">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <a href="http://vertx.io/" class="navbar-brand"><img alt="Brand" src="http://vertx.io/assets/logo-sm.png"></a>
    </div>
    <nav class="collapse navbar-collapse" id="vertx-navbar-collapse">
      <ul class="nav navbar-nav navbar-right">
        <li><a href="http://vertx.io/download/">Download</a></li>
        <li><a href="http://vertx.io/docs/">Documentation</a></li>
        <li><a href="https://github.com/vert-x3/wiki/wiki">Wiki</a></li>
        <li><a href="http://vertx.io/community/">Community</a></li>
        <li><a href="http://vertx.io/materials/">Materials</a></li>
        <li><a href="http://vertx.io/blog/">Blog</a></li>        
      </ul>
    </nav>
  </div>
</header>



  <div class="page-header" id="content">
    <div class="container">
      <div class="row">
        <div class="col-sm-12">
          <h1>Apache Ignite Cluster Manager for Vert.x</h1>
          
        </div>
      </div>
    </div>
  </div>




<div id="content">
  <div class="container docs-content">
    <div class="row">
      <div class="col-sm-12 col-md-push-9 col-md-3 hidden-xs hidden-sm">
        <div id="sidebar" data-spy="affix">
          <ul class="sectlevel1">
<li><a href="#_using_ignite_cluster_manager">Using Ignite cluster manager</a>
<ul class="sectlevel2">
<li><a href="#_using_vert_x_from_command_line">Using Vert.x from command line</a></li>
<li><a href="#_using_vert_x_in_maven_or_gradle_project">Using Vert.x in Maven or Gradle project</a></li>
<li><a href="#_programmatically_specifying_cluster_manager">Programmatically specifying cluster manager</a></li>
</ul>
</li>
<li><a href="#_configuring_cluster_manager">Configuring cluster manager</a>
<ul class="sectlevel2">
<li><a href="#_using_configuration_file">Using configuration file</a></li>
<li><a href="#_configuring_programmatically">Configuring programmatically</a></li>
<li><a href="#_discovery_and_network_transport_configuration">Discovery and network transport configuration</a></li>
</ul>
</li>
<li><a href="#_trouble_shooting_clustering">Trouble shooting clustering</a>
<ul class="sectlevel2">
<li><a href="#_multicast_not_enabled_on_the_machine">Multicast not enabled on the machine.</a></li>
<li><a href="#_using_wrong_network_interface">Using wrong network interface</a></li>
<li><a href="#_using_a_vpn">Using a VPN</a></li>
<li><a href="#_when_multicast_is_not_available">When multicast is not available</a></li>
<li><a href="#_enabling_logging">Enabling logging</a></li>
</ul>
</li>
</ul>
        </div>
      </div>
      <div class="col-sm-12 col-md-pull-3 col-md-9">
        <div class="toc hidden-md hidden-lg">
          <h2>Table of Contents</h2>
          <ul class="sectlevel1">
<li><a href="#_using_ignite_cluster_manager">Using Ignite cluster manager</a>
<ul class="sectlevel2">
<li><a href="#_using_vert_x_from_command_line">Using Vert.x from command line</a></li>
<li><a href="#_using_vert_x_in_maven_or_gradle_project">Using Vert.x in Maven or Gradle project</a></li>
<li><a href="#_programmatically_specifying_cluster_manager">Programmatically specifying cluster manager</a></li>
</ul>
</li>
<li><a href="#_configuring_cluster_manager">Configuring cluster manager</a>
<ul class="sectlevel2">
<li><a href="#_using_configuration_file">Using configuration file</a></li>
<li><a href="#_configuring_programmatically">Configuring programmatically</a></li>
<li><a href="#_discovery_and_network_transport_configuration">Discovery and network transport configuration</a></li>
</ul>
</li>
<li><a href="#_trouble_shooting_clustering">Trouble shooting clustering</a>
<ul class="sectlevel2">
<li><a href="#_multicast_not_enabled_on_the_machine">Multicast not enabled on the machine.</a></li>
<li><a href="#_using_wrong_network_interface">Using wrong network interface</a></li>
<li><a href="#_using_a_vpn">Using a VPN</a></li>
<li><a href="#_when_multicast_is_not_available">When multicast is not available</a></li>
<li><a href="#_enabling_logging">Enabling logging</a></li>
</ul>
</li>
</ul>
        </div>
        <div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>This is a cluster manager implementation for Vert.x that uses <a href="http://ignite.apache.org/index.html">Apache Ignite</a>.</p>
</div>
<div class="paragraph">
<p>In Vert.x a cluster manager is used for various functions including:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Discovery and group membership of Vert.x nodes in a cluster</p>
</li>
<li>
<p>Maintaining cluster wide topic subscriber lists (so we know which nodes are interested in which event bus
addresses)</p>
</li>
<li>
<p>Distributed Map support</p>
</li>
<li>
<p>Distributed Locks</p>
</li>
<li>
<p>Distributed Counters</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Cluster managers <strong>do not</strong> handle the event bus inter-node transport, this is done directly by Vert.x with TCP
connections.</p>
</div>
<div class="paragraph">
<p>Vert.x cluster manager is a pluggable component, so you can pick the one you want, or the one that is the most
adapted to your environment. So you can replace default Vert.x cluster manager by this implementation.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_using_ignite_cluster_manager">Using Ignite cluster manager</h2>
<div class="sectionbody">
<div class="paragraph">
<p>If the jar is on your classpath then Vert.x will automatically detect this and use it as the cluster manager.
Please make sure you don’t have any other cluster managers on your classpath or Vert.x might choose the wrong one.</p>
</div>
<div class="paragraph">
<p>Alternatively, you can configure the following system property to instruct vert.x to use this cluster manager:
<code>-Dvertx.clusterManagerFactory=io.vertx.spi.cluster.ignite.IgniteClusterManager</code></p>
</div>
<div class="sect2">
<h3 id="_using_vert_x_from_command_line">Using Vert.x from command line</h3>
<div class="paragraph">
<p><code>vertx-ignite-3.3.3.jar</code> should be in the <code>lib</code> directory of the Vert.x installation.</p>
</div>
</div>
<div class="sect2">
<h3 id="_using_vert_x_in_maven_or_gradle_project">Using Vert.x in Maven or Gradle project</h3>
<div class="paragraph">
<p>Add a dependency to the artifact.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Maven (in your <code>pom.xml</code>):</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-xml" data-lang="xml">&lt;dependency&gt;
  &lt;groupId&gt;io.vertx&lt;/groupId&gt;
  &lt;artifactId&gt;vertx-ignite&lt;/artifactId&gt;
  &lt;version&gt;3.3.3&lt;/version&gt;
&lt;/dependency&gt;</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>Gradle (in your <code>build.gradle</code> file):</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-groovy" data-lang="groovy">compile 'io.vertx:vertx-ignite:3.3.3'</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_programmatically_specifying_cluster_manager">Programmatically specifying cluster manager</h3>
<div class="paragraph">
<p>You can also specify the cluster manager programmatically. In order to do this just specify it on the options
when you are creating your Vert.x instance, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">ClusterManager clusterManager = new IgniteClusterManager();

VertxOptions options = new VertxOptions().setClusterManager(clusterManager);
Vertx.clusteredVertx(options, res -&gt; {
  if (res.succeeded()) {
    Vertx vertx = res.result();
  } else {
    // failed!
  }
});</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_configuring_cluster_manager">Configuring cluster manager</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_using_configuration_file">Using configuration file</h3>
<div class="paragraph">
<p>The cluster manager is configured by a file <code>default-ignite.xml</code> which is packaged inside the jar.</p>
</div>
<div class="paragraph">
<p>If you want to override this configuration you can provide <code>ignite.xml</code> file on your classpath and this will be
used instead.</p>
</div>
<div class="paragraph">
<p>The xml file is a Ignite configuration file and is described in details in
<a href="https://apacheignite.readme.io/docs">Apache Ignite documentation</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_configuring_programmatically">Configuring programmatically</h3>
<div class="paragraph">
<p>You can also specify configuration programmatically:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">IgniteConfiguration cfg = new IgniteConfiguration();
// Configuration code (omitted)

ClusterManager clusterManager = new IgniteClusterManager(cfg);

VertxOptions options = new VertxOptions().setClusterManager(clusterManager);
Vertx.clusteredVertx(options, res -&gt; {
  if (res.succeeded()) {
    Vertx vertx = res.result();
  } else {
    // failed!
  }
});</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_discovery_and_network_transport_configuration">Discovery and network transport configuration</h3>
<div class="paragraph">
<p>The default configuration uses <code>TcpDiscoveryMulticastIpFinder</code> so you must have multicast enabled on your network.
For cases when multicast is disabled <code>TcpDiscoveryVmIpFinder</code> should be used with pre-configured list of IP addresses.
Please see <a href="http://apacheignite.readme.io/docs/cluster-config">Cluster Configuration</a> section
at Apache Ignite documentation for details.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_trouble_shooting_clustering">Trouble shooting clustering</h2>
<div class="sectionbody">
<div class="paragraph">
<p>If the default multicast configuration is not working here are some common causes:</p>
</div>
<div class="sect2">
<h3 id="_multicast_not_enabled_on_the_machine">Multicast not enabled on the machine.</h3>
<div class="paragraph">
<p>By default the cluster manager is using <code>TcpDiscoveryMulticastIpFinder</code>, so IP multicasting is required,
on some systems, multicast route(s) need to be added to the routing table otherwise, the default route will be used.</p>
</div>
<div class="paragraph">
<p>Note that some systems don&#8217;t consult the routing table for IP multicast routing, only for unicast routing</p>
</div>
<div class="paragraph">
<p>MacOS example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre># Adds a multicast route for 224.0.0.1-231.255.255.254
sudo route add -net 224.0.0.0/5 127.0.0.1

# Adds a multicast route for 232.0.0.1-239.255.255.254
sudo route add -net 232.0.0.0/5 192.168.1.3</pre>
</div>
</div>
<div class="paragraph">
<p>Please google for more information.</p>
</div>
</div>
<div class="sect2">
<h3 id="_using_wrong_network_interface">Using wrong network interface</h3>
<div class="paragraph">
<p>If you have more than one network interface on your machine (and this can also be the case if you are running
VPN software on your machine), then Apache Ignite may be using the wrong one.</p>
</div>
<div class="paragraph">
<p>To tell Ignite to use a specific interface you can provide the IP address of the interface to the
bean of <code>IgniteConfiguration</code> type using <code>localHost</code> property. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>&lt;bean class="org.apache.ignite.configuration.IgniteConfiguration"&gt;
  &lt;property name="localHost" value="192.168.1.20"/&gt;
&lt;/bean&gt;</pre>
</div>
</div>
<div class="paragraph">
<p>When running Vert.x is in clustered mode, you should also make sure that Vert.x knows about the correct interface.
When running at the command line this is done by specifying the <code>cluster-host</code> option:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>vertx run myverticle.js -cluster -cluster-host your-ip-address</pre>
</div>
</div>
<div class="paragraph">
<p>Where <code>your-ip-address</code> is the same IP address you specified in the Apache Ignite configuration.</p>
</div>
<div class="paragraph">
<p>If using Vert.x programmatically you can specify this using <code><a href="../../apidocs/io/vertx/core/VertxOptions.html#setClusterHost-java.lang.String-">setClusterHost</a></code>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_using_a_vpn">Using a VPN</h3>
<div class="paragraph">
<p>This is a variation of the above case. VPN software often works by creating a virtual network interface which often
doesn&#8217;t support multicast. If you have a VPN running and you do not specify the correct interface to use in both the
Ignite configuration and to Vert.x then the VPN interface may be chosen instead of the correct interface.</p>
</div>
<div class="paragraph">
<p>So, if you have a VPN running you may have to configure both the Ignite and Vert.x to use the correct interface as
described in the previous section.</p>
</div>
</div>
<div class="sect2">
<h3 id="_when_multicast_is_not_available">When multicast is not available</h3>
<div class="paragraph">
<p>In some cases you may not be able to use multicast as it might not be available in your environment. In that case
you should configure another transport using corresponding IP finder, e.g. <code>TcpDiscoveryVmIpFinder</code> to use TCP sockets,
or <code>TcpDiscoveryS3IpFinder</code> to use Amazon S3.</p>
</div>
<div class="paragraph">
<p>For more information on available Ignite transports and how to configure them please consult the
<a href="https://apacheignite.readme.io/docs/clustering">Ignite Clustering</a> documentation.</p>
</div>
</div>
<div class="sect2">
<h3 id="_enabling_logging">Enabling logging</h3>
<div class="paragraph">
<p>When trouble-shooting clustering issues it&#8217;s often useful to get some logging output from Ignite
to see if it&#8217;s forming a cluster properly. You can do this (when using the default JUL logging) by adding a file
called <code>vertx-default-jul-logging.properties</code> on your classpath. This is a standard java.util.loging (JUL)
configuration file. Inside it set:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>org.apache.ignite.level=INFO</pre>
</div>
</div>
<div class="paragraph">
<p>and also</p>
</div>
<div class="listingblock">
<div class="content">
<pre>java.util.logging.ConsoleHandler.level=INFO
java.util.logging.FileHandler.level=INFO</pre>
</div>
</div>
</div>
</div>
</div>

        

        
          <div id="footer">
            <div id="footer-text">
              
                Last updated 2016-09-12 08:38:04 CEST
              
              
            </div>
          </div>
        
      </div>
    </div>
  </div>
</div>

<footer>
  <div class="container">
    <div class="row">
      <div class="col-xs-6 col-sm-3 col-md-3 col-lg-2">
        <h2>Vert.x</h2>
        <ul class="list-unstyled">
          <li><a href="http://vertx.io/">Home</a></li>
          <li><a href="http://vertx.io/download/">Download</a></li>
          <li><a href="http://vertx.io/docs/">Documentation</a></li>
          <li><a href="https://github.com/vert-x3/wiki/wiki">Wiki</a></li>
          <li><a href="http://vertx.io/blog/">Blog</a></li>
          <li><a href="http://vertx.io/vertx2/" class="vertx-2-link">Vert.x 2</a></li>
        </ul>
      </div>
      <div class="col-xs-6 col-sm-3 col-md-3 col-lg-2">
        <h2>Community</h2>
        <ul class="list-unstyled">
          <li><a href="http://vertx.io/community/">Help &amp; Contributors</a></li>
          <li><a href="http://vertx.io/materials/">Learning materials</a></li>
          <li><a href="https://groups.google.com/forum/?fromgroups#!forum/vertx">User Group</a></li>
          <li><a href="https://groups.google.com/forum/?fromgroups#!forum/vertx-dev">Developer Group</a></li>
        </ul>
      </div>

      <div class="col-xs-12 col-sm-6 col-lg-offset-2 col-md-6 copyright">
        <p>Vert.x is open source and dual licensed under the <a href="https://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License 1.0</a> and <a href="https://www.apache.org/licenses/LICENSE-2.0.html">Apache License 2.0</a>.</p>
        <p>This website is licensed under the <a href="http://creativecommons.org/licenses/by-sa/3.0/">CC BY-SA 3.0 License</a>.<br>
        Design by <a href="http://www.michel-kraemer.com">Michel Kr&auml;mer</a>. <a href="http://www.entypo.com">Entypo pictograms</a> by Daniel Bruce.</p>
        <div class="row">
          <div class="col-xs-12 col-lg-offset-1 col-md-5">
            <a href="http://eclipse.org">
            <img class="logo eclipse-logo" src="http://vertx.io/assets/eclipse_logo_grey_small.png" width="204" height="48">
            </a>
          </div>
          <div class="col-xs-12 col-md-offset-2 col-lg-offset-0 col-md-5">
            <a href="http://cloudbees.com">
            <img class="logo cloudbees-logo" src="http://vertx.io/assets/Button-Built-on-CB-1-grey.png" width="180" height="48">
           </a>
          </div>
          <div class="col-xs-12 col-md-offset-2 col-lg-offset-1 col-md-5 jprofiler">
            <a href="http://www.ej-technologies.com/products/jprofiler/overview.html"
            style="text-decoration:none">
            <img class="logo jprofiler-logo" src="http://vertx.io/assets/jprofiler-logo.png" width="48" height="48"><span class="jprofiler-logo">&nbsp; JPROFILER</span>
            </a>
          </div>
        </div>
      </div>
    </div>
  </div>
</footer>

<script src="http://static.jboss.org/theme/js/libs/jquery/jquery-1.9.1.min.js"></script>
<script src="http://vertx.io/javascripts/bootstrap.min.js"></script>
<script src="http://vertx.io/javascripts/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>



<script src="http://vertx.io/javascripts/sidebar.js"></script>


</body>
</html>
